docs: document automated translation updates by MartinKrzykawski · Pull Request #2410 · shopware/docs

Martin Krzykawski (MartinKrzykawski) · 2026-07-30T08:53:49Z

Summary

Documents the automated part of the translation workflow, which was not covered anywhere so far. New article
concepts/framework/translations/automated-translation-updates.md describes both halves of the chain:

Upstream (Crowdin): how en-GB source snippets and the de-DE translation are collected from
shopware/shopware into shopware/translations, uploaded to Crowdin, translated and approved by contributors, and
downloaded back into a reviewed pull request together with the crowdin-metadata.json update. Includes the daily
schedule of the three workflows, the entry point for contributors (translate.shopware.com),
why source strings are changed in code instead of in Crowdin, and the known review pitfalls (snippets containing
HTML, diffs in the source languages).
Downstream (shop): the translation.update scheduled task — default interval, what it does on each run,
its requirements (background worker, outbound HTTPS, private filesystem), how to inspect, trigger, or deactivate it,
what it explicitly does not do (install locales, change the active flag, override database snippets, remove
languages), failure handling, and a troubleshooting table.

Supporting adjustments:

Cross-links from built-in-translation-system.md, the translations index.md, and extension-points.md.
translation.update added to the default scheduled tasks in guides/hosting/infrastructure/scheduled-task.md,
including the note that it only runs when a translation is installed.
Completed the translation section of the command reference (translation:update, translation:list,
translation:lint-filenames, translation:validate).
Fixed the wrong command name snippet:validate to translation:validate in extension-points.md.

Checklist

I reviewed affected links, code samples, and cross-references, including PageRef references where relevant.
I added or updated redirects in .gitbook.yaml if pages were moved, renamed, or deleted. — not applicable, no page was moved or renamed
I updated .wordlist.txt (and sorted it) if spellcheck flags new legitimate terms. — not needed, spellcheck passes unchanged
Any required dependent changes in downstream modules have already been merged and published.
This pull request is ready for review.

Notes

Two points for the reviewer:

The article states that the scheduled task is available starting with 6.7.13.0, which is not released yet at the
time of writing (the task landed on 6.7.13.x). Please confirm the version before merging.
Nothing in trunk consumes the translation Admin API endpoints from the Administration yet, so the article
deliberately mentions only the CLI. The Administration part is a follow-up and will be documented together with
that implementation.

Verified locally: markdownlint and the spellcheck (make spellcheck-local) pass, and all relative links, anchors, and
PageRef targets resolve. All statements about the task, the commands, and the pipeline were checked against the code
in shopware/shopware and the workflows on shopware/translations@main.

Adds a dedicated article for the two automated halves of the translation workflow that were previously undocumented: - the upstream Crowdin pipeline: how en-GB/de-DE source snippets are collected from shopware/shopware, uploaded to Crowdin, translated and approved by contributors, and downloaded back into shopware/translations including the metadata that installations compare against - the downstream `translation.update` scheduled task: interval, what it does on each run, its requirements, how to inspect, trigger or deactivate it, what it explicitly does not do, and failure handling Cross-links the new page from the built-in translation handling page, the translations index, and the extension points page. Adds the task to the list of default scheduled tasks in the hosting guide and completes the translation section of the command reference. Fixes the command name `snippet:validate` to `translation:validate`.

shopware-dev-docs-connector · 2026-07-30T08:53:56Z

Developer Docs healthcheck

Status: Completed with success.
Repository: shopware/docs
Commit: f90abdc
Preview: https://developer-documentation-fqllrvdwi-shopware-frontends.vercel.app
Workflow run: #4660

github-actions · 2026-07-30T08:54:06Z

📊 Documentation Impact Analyzer

Metric	Result
Score	34
Recommendation	✅ Highly meaningful
Categories	Framework

Reasons

+4: Framework
+10: 5 new headings
+4: Code examples
+4: Framework
+4: 2 new headings
+4: Framework
+4: Framework

This score is automatically generated based on documentation impact heuristics.

Copilot

Pull request overview

Adds missing documentation for Shopware’s automated translation update workflow, covering both the upstream Crowdin/GitHub Actions pipeline and the downstream translation.update scheduled task in Shopware, and wires this new documentation into existing translation-related pages.

Changes:

Adds a new concept page describing the end-to-end automated translation update chain (Crowdin ↔ shopware/translations ↔ Shopware scheduled task).
Adds/adjusts cross-links across translation docs and scheduled task documentation.
Completes/aligns the command reference for translation-related CLI commands.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
resources/references/core-reference/commands-reference.md	Adds missing translation CLI commands to the command reference table.
guides/hosting/infrastructure/scheduled-task.md	Documents `translation.update` as a default scheduled task and adds contextual notes/linking.
concepts/framework/translations/index.md	Adds the new automated translation updates page to the translations section index.
concepts/framework/translations/extension-points.md	Fixes the command name to `translation:validate` and links to the new automation docs.
concepts/framework/translations/built-in-translation-system.md	Cross-links to the new automation page and notes the scheduled task behavior.
concepts/framework/translations/automated-translation-updates.md	Introduces the new end-to-end documentation page for automated translation updates.

Comments suppressed due to low confidence (2)

concepts/framework/translations/automated-translation-updates.md:122

The docs table guidelines recommend introducing tables with a complete sentence (resources/guidelines/documentation-guidelines/04-fonts-and-formats/01-text.md:105). Consider adding an explicit lead-in before this properties table.


| Property               | Value                                                                  |

concepts/framework/translations/automated-translation-updates.md:195

Per the documentation table guidelines, table rows should not end sentences with punctuation and tables should be introduced with a complete sentence (resources/guidelines/documentation-guidelines/04-fonts-and-formats/01-text.md:101-106). This troubleshooting table currently has no lead-in sentence, and several cells end sentences with periods.

## Troubleshooting

| Symptom                                                     | Cause and solution                                                                                                                              |
|-------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| The task never runs                                         | No background worker is consuming the queue. See [Scheduled Task](../../../guides/hosting/infrastructure/scheduled-task.md).                     |

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Fix the link in the scheduled task info box: the "built-in translation system" phrase pointed at the automation page instead of the built-in translation handling page. The automation page is now linked from a separate sentence, so each link text matches its target. Also correct the surrounding grammar in that sentence. Introduce the schedule, task properties, and troubleshooting tables with a lead-in sentence, and drop the sentence-final punctuation from the troubleshooting cells, as required by the table rules in resources/guidelines/documentation-guidelines/04-fonts-and-formats/01-text.md.

github-actions · 2026-07-30T12:38:19Z

📊 Documentation Impact Analyzer

Metric	Result
Score	34
Recommendation	✅ Highly meaningful
Categories	Framework

Reasons

+4: Framework
+10: 5 new headings
+4: Code examples
+4: Framework
+4: 2 new headings
+4: Framework
+4: Framework

This score is automatically generated based on documentation impact heuristics.

Co-authored-by: Marcel Brode <40024364+marcelbrode@users.noreply.github.com>

github-actions · 2026-07-31T06:13:51Z

📊 Documentation Impact Analyzer

Metric	Result
Score	34
Recommendation	✅ Highly meaningful
Categories	Framework

Reasons

+4: Framework
+10: 5 new headings
+4: Code examples
+4: Framework
+4: 2 new headings
+4: Framework
+4: Framework

This score is automatically generated based on documentation impact heuristics.

github-actions · 2026-07-31T06:14:04Z

📊 Documentation Impact Analyzer

Metric	Result
Score	34
Recommendation	✅ Highly meaningful
Categories	Framework

Reasons

+4: Framework
+10: 5 new headings
+4: Code examples
+4: Framework
+4: 2 new headings
+4: Framework
+4: Framework

This score is automatically generated based on documentation impact heuristics.

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (2)

concepts/framework/translations/automated-translation-updates.md:118

This note asserts the scheduled task is available starting with Shopware 6.7.13.0, but the PR description mentions this version is not confirmed yet. To avoid publishing potentially incorrect version information, please either confirm the exact version before merge or soften the statement to reflect that it’s pending confirmation.

::: info
The scheduled task is available starting with Shopware 6.7.13.0. In older versions, translations are updated only by
running the `translation:update` command.

resources/references/core-reference/commands-reference.md:416

In this translation commands table, the translation:pull and translation:push description cells end with a period, which conflicts with the documentation guideline to not end table entries with punctuation. Since this PR touches this table section, it’s a good opportunity to make the table consistent by removing the trailing periods.

| `translation:lint-filenames` | Ensures translations have a country-agnostic translation file as a base and renames them with `--fix`                    |
| `translation:list`    | Lists all locales that are configured for `translation:install` and `translation:update`                                        |
| `translation:pull`    | Pulls translations from a given provider.                                                                                      |
| `translation:push`    | Pushes translations to a given provider.                                                                                       |

Restructure the delivery chain diagram: declare each node label where the node first appears, highlight the repository and project names, and label the last edge "daily by default" instead of "per installation". The schedule table now uses the same wording. The suggested diagram snippet is applied with two deviations, both because mermaid would not render them: a markdown link inside an HTML node label stays plain text, and the edge label drops its backticks, which would otherwise show up as literal characters. Further changes: * State that a source snippet change needs a pull request. * Estimate the Crowdin-to-shop latency in workdays, since the gating step is a maintainer review rather than one of the daily workflows. * Link the Crowdin project once instead of twice. * Do not claim that every official plugin contributes translation files. * Name the repository the release branch belongs to.

github-actions · 2026-07-31T12:26:20Z

📊 Documentation Impact Analyzer

Metric	Result
Score	34
Recommendation	✅ Highly meaningful
Categories	Framework

Reasons

+4: Framework
+10: 5 new headings
+4: Code examples
+4: Framework
+4: 2 new headings
+4: Framework
+4: Framework

This score is automatically generated based on documentation impact heuristics.

Marcel Brode (marcelbrode) · 2026-07-31T12:34:13Z

AI Suggestion: The Administration branch (shopware/shopware#18320) introduces a per-language translationAutoUpdate flag (BoolField, default true), and the scheduled task now filters on it — UpdateTranslationsTaskHandler applies EqualsFilter('translationAutoUpdate', true) and passes only those locales to TranslationUpdater::updateInstalled(). That makes four statements in concepts/framework/translations/automated-translation-updates.md inaccurate. Suggested edits below (line numbers as of the current head):

1. Line 135 — "On every run, the handler refreshes all currently installed translations:"

On every run, the handler refreshes the installed translations of every language whose automatic updates are enabled (the `translationAutoUpdate` flag, on by default):

2. Lines 144–145 — the CLI equivalence claim. translation:update (CLI) refreshes every installed locale, while the scheduled task is scoped to languages with translationAutoUpdate enabled — same service method, different scope, so they are no longer equivalent.

`bin/console translation:update` performs the same kind of refresh through the same service, but it is not scoped: it updates every installed translation. The scheduled task, in contrast, only updates languages whose `translationAutoUpdate` flag is enabled.

3. Line 185 — add a bullet in "What the task does not do" for the per-language opt-out:

* **It does not update languages with automatic updates disabled.** A language whose `translationAutoUpdate` flag is off is skipped, even when a newer translation is available.
* **It does not remove languages** when a locale disappears from the translations repository.

4. Line 201 — Troubleshooting row "The task runs but nothing changes", add the disabled flag as a cause:

| The task runs but nothing changes             | No installed locale has a newer remote `updatedAt` timestamp, the language has `translationAutoUpdate` disabled, or no translation is installed at all. Run `bin/console translation:list` — locales without a **Last update** value are not installed |

The task calls TranslationUpdater::updateInstalled(), while translation:update drives TranslationMetadataStore and the translation loader directly. They compare the same metadata and update the same locales, but they are not the same service, so the page no longer claims they are.

github-actions · 2026-08-03T08:39:38Z

📊 Documentation Impact Analyzer

Metric	Result
Score	34
Recommendation	✅ Highly meaningful
Categories	Framework

Reasons

+4: Framework
+10: 5 new headings
+4: Code examples
+4: Framework
+4: 2 new headings
+4: Framework
+4: Framework

This score is automatically generated based on documentation impact heuristics.

The scheduled task filters languages on `translationAutoUpdate` and only passes the matching locales to the updater, so describe the language query as the first step, note the per-language opt-out, and add the disabled flag as a cause in the troubleshooting table. `translation:update` is not scoped by the flag, so the page states the difference instead of calling the two interchangeable.

Martin Krzykawski (MartinKrzykawski) · 2026-08-03T08:48:49Z

All four points are in as of f90abdc — since you are adding the Admin UI part as a commit here, both land together and the milestone difference does not matter. I verified the behaviour against #18320 first: translation_auto_update is a TINYINT(1) NOT NULL DEFAULT 1, LanguageDefinition exposes it as BoolField('translation_auto_update', 'translationAutoUpdate'), and UpdateTranslationsTaskHandler::run() filters with EqualsFilter('translationAutoUpdate', true) before passing the locales into TranslationUpdater::updateInstalled($context, $locales).

What changed:

The lead-in now says the handler refreshes the installed translations of every language whose automatic updates are enabled.
"What the task does" got a new first step. Your suggestions covered the lead-in, but the numbered steps still described the old flow — metadata first, then update everything. The handler now queries the languages first and returns before touching the metadata when nothing qualifies, so step 1 is the language query and the metadata read moved to step 2. Without that the section contradicted its own intro.
New bullet in "What the task does not do" for the per-language opt-out, pointing at translation:update as the way to refresh a disabled language anyway.
Troubleshooting row extended with the disabled flag as a cause.

Two deliberate deviations from your suggestions, both about translation:update:

I dropped "through the same service". The command never touches TranslationUpdater — UpdateTranslationCommand::execute() drives TranslationMetadataStore::getUpdatedLocalMetadata() and AbstractTranslationLoader::load() directly. Your conclusion was right, the premise was not, and it caught a sentence of mine that was already wrong on trunk. It now reads: "bin/console translation:update performs the same kind of refresh, but it is not scoped: it updates every installed translation, regardless of the translationAutoUpdate flag. The two also run through different code paths, so do not rely on one to report what the other did."
I added one line to the version info box saying the flag follows in 6.7.14.0, since the task itself is 6.7.13.0 and someone on that version will not find the flag. Drop it if you would rather keep the box to a single version.

make spellcheck-local and markdownlint both pass locally. The 6.7.13.0 claim in that same box is still the one thing nobody has confirmed — if you can confirm it while you are in there, this is done from my side.

github-actions · 2026-08-03T08:49:14Z

📊 Documentation Impact Analyzer

Metric	Result
Score	34
Recommendation	✅ Highly meaningful
Categories	Framework

Reasons

+4: Framework
+10: 5 new headings
+4: Code examples
+4: Framework
+4: 2 new headings
+4: Framework
+4: Framework

This score is automatically generated based on documentation impact heuristics.

Copilot AI review requested due to automatic review settings July 30, 2026 08:53

Martin Krzykawski (MartinKrzykawski) self-assigned this Jul 30, 2026

Copilot started reviewing on behalf of Martin Krzykawski (MartinKrzykawski) July 30, 2026 08:54 View session

Copilot AI reviewed Jul 30, 2026

View reviewed changes

Comment thread guides/hosting/infrastructure/scheduled-task.md Outdated

Comment thread concepts/framework/translations/automated-translation-updates.md

Martin Krzykawski (MartinKrzykawski) added the added Added content label for changelog label Jul 30, 2026

Martin Krzykawski (MartinKrzykawski) requested a review from Marcel Brode (marcelbrode) July 30, 2026 12:44

Marcel Brode (marcelbrode) requested changes Jul 30, 2026

View reviewed changes

Comment thread concepts/framework/translations/automated-translation-updates.md Outdated

Comment thread concepts/framework/translations/automated-translation-updates.md Outdated

Martin Krzykawski (MartinKrzykawski) and others added 2 commits July 31, 2026 08:13

Update concepts/framework/translations/automated-translation-updates.md

222dcef

Co-authored-by: Marcel Brode <40024364+marcelbrode@users.noreply.github.com>

Update concepts/framework/translations/automated-translation-updates.md

b45ba1f

Co-authored-by: Marcel Brode <40024364+marcelbrode@users.noreply.github.com>

Martin Krzykawski (MartinKrzykawski) requested a review from Marcel Brode (marcelbrode) July 31, 2026 06:14

Martin Krzykawski (MartinKrzykawski) requested a review from Copilot July 31, 2026 09:11

Copilot started reviewing on behalf of Martin Krzykawski (MartinKrzykawski) July 31, 2026 09:12 View session

Copilot AI reviewed Jul 31, 2026

View reviewed changes

Marcel Brode (marcelbrode) requested changes Jul 31, 2026

View reviewed changes

Martin Krzykawski (MartinKrzykawski) requested a review from Marcel Brode (marcelbrode) July 31, 2026 12:28

Marcel Brode (marcelbrode) approved these changes Aug 3, 2026

View reviewed changes

Martin Krzykawski (MartinKrzykawski) requested a review from Su (sushmangupta) August 3, 2026 12:29

Uh oh!

Conversation

Martin Krzykawski (MartinKrzykawski) commented Jul 30, 2026

Summary

Related links

Checklist

Notes

Uh oh!

shopware-dev-docs-connector Bot commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Developer Docs healthcheck

Uh oh!

github-actions Bot commented Jul 30, 2026

📊 Documentation Impact Analyzer

Reasons

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jul 30, 2026

📊 Documentation Impact Analyzer

Reasons

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jul 31, 2026

📊 Documentation Impact Analyzer

Reasons

Uh oh!

github-actions Bot commented Jul 31, 2026

📊 Documentation Impact Analyzer

Reasons

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jul 31, 2026

📊 Documentation Impact Analyzer

Reasons

Uh oh!

Marcel Brode (marcelbrode) commented Jul 31, 2026

Uh oh!

github-actions Bot commented Aug 3, 2026

📊 Documentation Impact Analyzer

Reasons

Uh oh!

Martin Krzykawski (MartinKrzykawski) commented Aug 3, 2026

Uh oh!

github-actions Bot commented Aug 3, 2026

📊 Documentation Impact Analyzer

Reasons

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

shopware-dev-docs-connector Bot commented Jul 30, 2026 •

edited

Loading